home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / 105_01.zip / FLOATXT.DOC < prev    next >
Text File  |  1993-06-09  |  9KB  |  286 lines
  1.  
  2.         The Incredible Superpowerful 
  3.         Floating Point Package for BDS C v1.4
  4.         *************************************
  5.         software written by: Bob Mathias
  6.         this documentation by: Leor Zolman
  7.  
  8.     Components of the floating point package:
  9.  
  10.         1)    FLOAT.DOC:    This documentation file
  11.         2)    FLOAT.C:    File of support functions, written in C
  12.         3)    FP:        The workhorse function (in DEFF2.CRL)
  13.         4)  FLOATSUM.C    A Sample use of all this stuff
  14.  
  15. EXTENDED VERSION ADDING FIVE USEFUL FUNCTION & 1 FIX  replaces::
  16.          1) FLOATXT.DOC    This documentation file
  17.          2) FLOATXT.C    File of support functions, with
  18.                  five added functions, written in C
  19.          3) FP        unchanged
  20.          4) FLEVAL        A small program to exercise the
  21.                  floating point conversions and
  22.                  operations.
  23.  
  24.  ***Added functions are magnitude, truncation to integer, rounded
  25.     truncation to integer, change sign, assignment ( = ).
  26.  
  27.  ***Quick summary table of floating point functions added at end
  28.     of general observations.
  29.  
  30.  * New functions described at end of description of old, just
  31.     before "General Observations.
  32.  
  33.    L.C. Calhoun
  34.    257 South Broadway
  35.    Lebanon, Ohio 45036    <513> 932 4541/433 7510
  36.  
  37.    And now, back to our scheduled show - -
  38.     This floating point package is as close as BDS C
  39. version 1.x is ever gonna come to manipulating floating point
  40. numbers. And it ain't too bad, actually...Bob did a nice neat
  41. job, and the new formatted printout support in a special version
  42. of the "_spr" library function (source is in FLOAT.C) means that
  43. floating point output is no longer limited to scientific notation.
  44.  
  45.     Here's how it works: for every floating point number
  46. you wish to work with, you must declare a five (5) element
  47. character array. Then, pass a pointer to the array whenever
  48. you need to specify it in a function call. Each of Bob's
  49. functions expects its arguments to be pointers to such 
  50. character arrays.
  51.  
  52.     The four basic arithmetic functions are: fpadd,
  53. fpsub, fpmul and fpdiv. They each take three arguments: a
  54. pointer to a five character array where the result will go,
  55. and the two operands (each a pointer to a five character array
  56. representing a floating point operand.)
  57.  
  58.     To facilitate the initialization of the floating
  59. point character arrays with the values you desire and printing
  60. out the values in a human-readable form, the following
  61. functions are included:
  62.  
  63.     ftoa: converts a floating point number to an ASCII
  64.           string (which you can then print out with "puts")
  65.           NOTE: explicit use of this function has been made
  66.             obsolete by the new "sprintf." See FLOAT.C.
  67.  
  68.     atof: converts an ASCII string (null terminated) to
  69.           a floating point number
  70.  
  71.     itof: converts integer to floating point.
  72.  
  73. Here are Bob's descriptions of the functions:
  74.  
  75.         -----------------------------------
  76.  
  77. The following functions allow BDS C compiler users to access
  78. and manipulate real numbers. Each real number must be allocated
  79. a five (5) byte character array (char fpno[5]).  The first four
  80. bytes contain the mantissa with the first byte being the least
  81. significant byte.  The fifth byte is the exponent.
  82.  
  83. fpcomp(op1,op2)
  84. char op1[5],op2[5];
  85.             Returns:
  86.             an integer 1 if op1 > op2
  87.             an integer -1 if op1 < op2
  88.             a zero if op1 = op2
  89.         As with most floating point packages, it is not
  90.         a good practice to compare for equality when
  91.         dealing with floating point numbers.
  92.  
  93. char *fpadd(result,op1,op2)
  94. char result[5], op1[5], op2[5];
  95.         Stores the result of op1 + op2 in result. op1
  96.         and op2 must be floating point numbers.
  97.         Returns a pointer to the beginning of result.
  98.  
  99.  
  100. char *fpsub(result,op1,op2)
  101. char result[5],op1[5],op2[5];
  102.         Stores the result of op1 - op2 in result.  op1
  103.         and op2 must be floating point numbers.  
  104.         Returns a pointer to the beginning of result.
  105.  
  106. char *fpmult(result,op1,op2)
  107. char result[5],op1[5],op2[5];
  108.         Stores the result of op1 * op2 in result.  op1
  109.         and op2 must be floating point numbers. Returns
  110.         a pointer to the beginning of result.
  111.            watch out for over/underflow which wrap
  112.              around in the exponent ! note by LCC
  113.  
  114. char *fpdiv(result,op1,op2)
  115. char result[5],op1[5],op2[5];
  116.         Stores the result of op1 / op2 in result.  op1
  117.         and op2 must be floating point numbers.  
  118.         A divide by zero will return zero as result.
  119.         Returns a pointer to the beginning of result.
  120.  
  121. char *atof(op1,s1)
  122. char op1[5],*s;
  123.         Converts the ASCII string s1 into a floating
  124.         point number and stores the result in op1.  
  125.         The function will ignore leading white space 
  126.         but NO white space is allowed to be embedded
  127.         withing the number. The following are legal
  128.         examples:
  129.         "2", "22022222222383.333", "2.71828e-9",
  130.         "334.3333E32".
  131.         "3443.33 E10" would be ILLEGAL because
  132.         it contains an embedded space.
  133.         The value of the exponent must be within the
  134.         range: -38 <= exponent <= 38.
  135.         A pointer to the result is returned.
  136.  
  137.  
  138. char *ftoa(s1,op1)
  139. char *s1,op1[5];
  140.         Converts the floating point number op1 to an 
  141.         ASCII string.  It will be formatted in 
  142.         scientific notation with seven (7) digits of
  143.         precision. The string will be terminated by
  144.         a null.
  145.         Returns a pointer to the beginning of s1.
  146.  
  147. char *itof(op1, n)
  148. char op1[5];
  149. int n;
  150.         Sets the floating pt. number op1 to the value
  151.         of integer n. n is assumed to be a SIGNED
  152.         integer.
  153.  
  154.     --------added new functions-------------
  155. int ftoit(fpno)
  156. char fpno[5];
  157.  
  158.     returns a truncated integer equivalent to the floating
  159.     point number fpno input.  Integer values larger than 32767
  160.     or less than -32767 will overflow in the same manner
  161.     as in atoi().  There are no error messages in this case.
  162.  
  163. int ftoir(fpno)
  164. char fpno[5];
  165.  
  166.     returns a rounded integer equivalent to the floating point
  167.     number fpno input.  Positive values are rounded by adding
  168.     0.5 to fpno prior to truncation.  Negative values are
  169.     rounded by subtracting 0.5 from fpno prior to truncation.
  170.  
  171. char *fpmag(result,fpno)
  172. char result[5], fpno[5];
  173.  
  174.     converts negative floating point numbers to positive
  175.     floating point numbers, and leaves positive numbers
  176.     positive.  returns pointer to result.
  177.  
  178. char *fpchs(result,fpno)
  179. char result[5], fpno[5];
  180.  
  181.     Changes the sign of fpno and places in result.  Returns
  182.      pointer to result.
  183.  
  184. char *fpasg(result,fpno)
  185. char result[5], fpno[5];
  186.  
  187.     Places fpno in result leaving fpno unchanged.  Simple
  188.      assignment
  189.  
  190.   The above new functions added by LCC
  191.  
  192. General observations:
  193.  
  194.     Because floating point operations must be thought of
  195. in terms of FUNCTION CALLS rather than simple in-line
  196. expressions, special care must be taken not to confuse the
  197. abilities of the compiler with the abilities of the floating
  198. point package. To give a floating point number an initail
  199. value, for instance, you cannot say:
  200.  
  201.     char fpno[5];
  202.     fpno = "2.236";
  203.  
  204. To achieve the desired result, you'd have to say:    
  205.  
  206.     char fpno[5];
  207.     atof(fpno,"2.236");
  208.  
  209. Moreover, let's say you want to set a floating point number
  210. to the value of an integer variable called "ival". Saying:
  211.  
  212.     char fpno[5];
  213.     int ival;
  214.     ...
  215.     fpno = ival;
  216.  
  217. will not work; you have to change that last line to:
  218.  
  219.     itof(fpno,ival);
  220.  
  221.     Some more examples:
  222.  
  223.     The following will add 100.2 & -7.99 and store the
  224.     result at the five character array location 'a':
  225.         fpadd(a,atof(b,"100.2"), atof(c,"-7.99"));
  226.     (note that "b" and "c" must also be five character
  227.     arrays)
  228.  
  229.     The following would NOT add 1 to 'a' as both op1 and 
  230.     op2 must be floating point numbers (actually pointers
  231.     to characters...):
  232.  
  233.         fpadd(a,a,1);  /* bad use of "fpadd" */
  234.  
  235.     Thus, it can get a bit hairy when all floating
  236. point numbers are really character arrays; but still, it's
  237. better than nothing.
  238.  
  239.     All of the above functions are written in C, but
  240. most of them call a single workhorse function called "fp"
  241. to do all the really hairy work. This function has been placed
  242. into the DEFF2.CRL; it is the only machine-coded part of the
  243. package.
  244.  
  245.     Questions on the internals of this package should
  246. be addressed to:
  247.  
  248.     Bob Mathias
  249.     23147 Los Alisos apt. 268
  250.     Mission Viejo, Ca. 92691
  251.  
  252. At Bob's request, the source for the "fp" function has not been
  253. included in the package and is not generally available. If you really
  254. need the thing, try contacting Bob at the above address and ask for
  255. it.
  256.  
  257.  
  258. --------------- TABLE OF FLOATING POINT EQUIVALENCIES -----------------
  259. Effect of Function    Function            Results
  260. ----------------------- ------------------------------- ---------------
  261. op1 > op2        int fpcomp(op1,op2)        fpcomp =  1
  262. op1 = op2 <remember fp>                    fpcomp =  0
  263. op1 < op2                        fpcomp = -1
  264.  
  265. result = op1 + op2    char *fpadd(result,op1,op2)    point to result
  266.  
  267. result = op1 - op2    char *fpsub(result,op1,op2)    point to result
  268.  
  269. result = op1 * op2    char *fpmult(result,op1,op2)    point to result
  270.  
  271. result = op1 / op2    char *fpdiv(result,op1,op2)    point to result
  272.  
  273. op1 = float(n)        char *itof(op1,n)        point to result
  274.  
  275. result = |fpno|        char *fpmag(result,fpno)    point to result
  276.  
  277. result = - fpno        char *fpchs(result,fpno)    point to result
  278.  
  279. result = fpno  <:=>    char *fpasg(result,fpno)    point to result
  280.  
  281. truncate integer fpno    int ftoit(fpno)            ftoit=INT(fpno)
  282.  
  283. round & integer fpno    int ftoir(fpno)            ftoir=INT(fpno)
  284.                             +round up
  285.                             -round down
  286.